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介绍 

SBT 是 一 个 灵活 强大 的 项 目 构建 工具 ， 相 上 比 其 他 构建 工具 用 起 来 会 发 现 简洁 简洁 ， 但 是 从 功 
能 上 看 一 点 都 逊色 于 其 他 构建 工具 。 


快速 入 门 可 以 帮助 您 快速 的 利用 SBT 构 建 或 维护 一 个 工程 ， 并 且 简 单 介 绍 了 一 些 配置 构建 工 
具 的 相关 概念 。 


如 果 你 已 经 熟悉 SBT 使 用 ， 可 以 直接 去 看 配置 文件 .sbt 、 配 置 作用 域 和 配置 参数 的 方法 相关 
章节 ， 不 过 建议 还 是 按照 快速 入 门 章节 顺序 阅读 ， 这 样 可 以 理解 SBT 的 相关 概念 。 


感谢 尝试 SBT 并 体验 其 中 的 乐趣 | 


A 
安装 SBT 
创建 一 个 用 SBT 构建 的 工程 大 致 需要 如 下 几 步 : 


。 安装 SBT 并 创建 一 个 启动 脚本 
。 创建 一 个 简单 的 项 目 ， 以 Hello World 为 例 
o 创建 项 目 目 录 和 项 目 代码 相关 文件 
o 配置 项 目 构建 定义 文件 
。 参考 运行 SBT 章 节 学 习 SBT 如 何 运行 
e 参考 配置 文件 .sbt 章 节 学 习 更 多 的 SBT 相关 定义 
基本 上 SBT 的 安装 可 以 归纳 为 一 个 Jar 文件 和 一 个 启动 脚本 ， 但 是 依赖 于 具体 的 平台 
供 了 几 种 平台 的 安装 步骤 ， 在 此 不 累 赣 叙述 了 。 


， 我 们 提 


第 三 方 的 包 可 能 没有 提供 最 新 版 本 ， 可 以 将 相关 任何 问题 反馈 给 包 相 关 的 维护 者 


通过 Macports 安装 


$ port install sbt 


通过 Homebrew 安装 

$ brew install sbt 
通过 通用 的 包 安 装 
FA ZIP 包 或 TGZ 包 解 压 
手动 安装 


参考 手动 安装 SBT 


Windows 平台 安装 SBT 
通过 Windows 安装 包 安 装 

下 载 msi 安装 包 并 安装 

通过 通用 的 包 安 装 

下 载 ZIP 包 或 TGZ 包 解 压 

手动 安装 


参考 手动 安装 SBT 


Linux 平台 安装 SBT 
通过 通用 的 包 安装 
下 载 ZIP 包 或 TGZ 包 解 压 


RPM 和 DEB 


。 RPM 包 
e DEB 包 


注意 : 请 将 任何 和 这 两 个 包 相 关 的 问题 反馈 到 sbt-launcher-package 项 目 issue 
Gentoo 


In the official tree there is no ebuild for sbt. But there are ebuilds to merge sbt from binaries. 
To merge sbt from this ebuilds you can do: 


$ mkdir -p /usr/local/portage && cd /usr/local/portage 

$ git clone git://github.com/whiter4bbit/overlays.git 

$ echo "PORTDIR_OVERLAY=$PORTDIR_ OVERLAY /usr/local/portage/overlays" >> /etc/make.con 
f 

$ emerge sbt-bin 


注意 : 有 任何 和 ebuild 相关 的 问题 请 反馈 到 ebuild issue 
手动 安装 


参考 手动 安装 SBT 


手动 安装 SBT 


Unix 
将 sbt-launch.jar 包 放 到 目录 ~/bin 中 


创建 一 个 运行 jar 包 的 脚本 ~/bin/sbt, 脚本 内 容 为 : 


SBT_OPTS="-Xms512M -Xmx1536M -Xss1M -XX:+CMSClassUnloadingEnabled -XX:MaxPermSize=256M 


java $SBT_OPTS -jar ‘dirname $0 /sbt-launch.jar "$@" 


确保 脚本 有 执行 权限 


$ chmod u+x -/bin/sbt 


简单 例子 : Hello World 


创建 项 目 目录 和 项 目 代 码 


一 个 合法 的 sbt 项 目 可 以 在 一 个 项 目 目录 中 包含 单个 文件 。 尝 试 创建 一 个 包含 hw.scala 文件 
的 目录 hello, 文件 中 的 内 容 如 下 : 


object Hi { 
def main(args: Array[String]) = printlin("Hi!") 
} 


现在 可 以 进入 目录 hello 运行 sbt 命令 ， 在 sbt 交 互 模式 下 运行 run 命令 ， 具 体 的 在 Unix 或 
OS X 中 的 命 全 令 如 下 : 


mkdir hello 

cd hello 

echo ‘object Hi { def main(args: Array[String]) = println("Hi!") }' > hw.scala 
sbt 


RAA 


> run 


Hi! 


在 这 种 情况 下 sbt 完全 遵循 一 套 构建 规则 的 ，sbt 会 自动 根据 规则 进行 构建 ， 具 体 的 规则 如 
FT : 


e 代码 源 文件 可 以 是 sbt 项 目 根 目录 

e 代码 源 文 件 可 以 是 在 src/main/scala À src/main/java 目录 
e 测试 代码 目录 为 src/test/scala 或 src/test/java 目录 

e 数据 文件 在 src/main/resources À src/test/resources 

e 依赖 的 jars 文件 可 以 放 到 lib 目录 下 


or sbt 构建 的 项 目 用 的 scala 版 本 和 sbt À As ie 的 ， 可 以 通过 
运行 sbt run 命令 或 sbt console 进入 Scala REPL 模式 下 运行 项 目 ，sbt 会 加 载 依赖 的 
classpath ， 以 可 以 使 用 sbt 直接 运行 测试 项 目 。 


构建 项 目的 配置 文件 


许多 项 目 都 需要 手动 进行 配置 ， 最 基本 的 配置 一 般 都 是 定义 在 根 目录 的 build.sbt 文件 中 ， 例 
如 ， 如 果 项 目 跟 目录 为 hello > Æ hello/build.sbt 中 可 能 为 : 


name := "hello" 
version := "1.0" 


scalaVersion := "2.10.3" 


需要 注意 的 是 每 个 配置 项 之 间 用 空 行 分 割 ， 这 个 不 仅仅 是 为 了 显示 ， 实 际 上 sbt 需要 根据 空 行 
来 分 割 多 个 配置 项 的 。 在 配置 文件 .sbt 章节 中 你 可 以 学 到 如 何 配置 build.sbt 


如 果 你 需要 将 项 目 打包 成 jar 包 ， 需 要 在 build.sbt 中 指定 名 称 和 最 新 版 本 号 。 


设置 SBT 版 本 


可 以 强制 使 用 某 个 sbt 版 本 在 构建 项 目的 时 候 ， 需 要 在 hello/project/build.properties 文件 中 配 
置 : 


sbt.version = 0.13.5 


强制 使 用 sbt 的 0.13.5 版 本 ， 虽 然 sbt MAN 99% 是 兼容 的 ， 不 过 设置 
hello/project/build.properties 指定 sbt 版 本 可 以 避免 版 本 之 问 不 兼容 叶 致 的 一 些 潜在 问题 。 


目录 结构 


根 目录 


在 sbt 术语 中 “ 根 目录 ”是 一 个 包含 项 目的 目录 ， 所 以 如 果 创 建 一 个 hello 项 目 将 包含 
hello/build.sbt 和 hello/hw.scala 在 hello world 项 目 例子 中 ， 其 中 hello 是 根 目录 


源 代码 目录 结构 


源 代码 可 以 放 到 项 目的 根 目 录 类 似 于 hello/hw.scala , 但 是 在 丨 正 的 项 目 很 少 利 用 这 样 的 代码 
结构 ， 这 样 会 使 项 目 变 得 混乱 ，sbt 的 项 目 目 录 结 构 默 认 情 况 下 和 Maven 一 样 (所 有 路 劲 是 
基于 根 目 录 的 相对 路 劲 ) : 


src/ 
main/ 
resources/ 
< 包含 在 main 的 jar 包 中 的 文件 > 
scala/ 
<scala 源 代码 > 
java/ 
<java 源 代码 > 
test/ 
resources/ 
< 包含 在 test 的 jar 包 中 的 文件 > 
scala/ 
<scala 源 代码 > 
java/ 
<java 源 代码 > 


除 src/ 目录 以 外 的 目录 将 被 忽略 ， 包 括 隐藏 的 目录 。 


sbt 构建 定义 文件 


你 已 经 在 项 目的 根 目 录 中 看 到 了 build.sbt ， 其 他 的 ER 目录 project 中 ， 
project 可 以 包含 scala 文件 ， 将 和 .sbt 定义 进行 合并 来 完成 构建 定义 ， 详 细 的 可 以 参 
考 scala 配置 定义 


build.sbt 
project/ 
Build.scala 


你 可 能 看 到 在 project/ 目录 中 有 一 个 .sbt 文件 ， 这 个 文件 和 根 目 录 中 的 .sbt 不 是 针对 
一 个 项 目的 定义 ， 稍 后 会 解释 这 一 


构建 项 目 


生成 的 文件 (编译 后 的 class 文 件 ，jar 包 ， 项 目 管理 文件 ， 缓 存 文 件 和 文档 ) 将 被 写 入 到 一 
AN target A KRU 


配置 项 目 版 本 控制 


项 目的 .gitignore 文件 中 应 该 包含 target/ ， 注 意 : 以 /结尾 (匹配 目录 中 所 有 目录 和 
文件 ) 并 且 开 头 不 包含 / (为 了 匹配 project/target/) 
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交互 模式 

在 根 目录 中 运行 sbt 命令 不 带 任何 参数 将 进入 交互 模式 


$ sbt 


交互 模式 有 一 个 命令 输入 功能 (可 以 用 Tab 补 全 和 历史 命令 ) ， 例 如 ， 当 输入 Compile 
时 : 


> compile 


如 果 再 次 编译 只 需 按 向 上 键 + 回 车 键 如 果 运 行 该 项 目 输入 run 如 果 退 出 交互 模式 输入 
exit 或 用 快捷 键 ctriro (Unix) À ctrl+z (Windows) 


批量 脚本 模式 


你 也 可 以 在 批量 脚本 模式 下 运行 sbt, 指定 一 个 用 空格 分 割 的 一 系列 命令 作为 参数 . 对 于 sbt À 
令 本 身 也 可 以 指定 对 应 的 参数 ， 将 命令 和 命令 参数 用 双 引 号 括 起 来 ， 其 中 一 个 参数 为 命令 
其 余 的 为 命令 参数 ， 例 如 


$ sbt clean compile "testOnly TestA TestB" 


在 这 个 例子 中 ，testOnly 有 两 个 参数 分 别 是 TestA 和 TestB. 这 个 命令 将 按照 
clean, compile, testOnly 顺序 来 执行 . 


持续 构建 于 测试 


为 了 提供 编辑 -编译 -测试 整个 周期 的 效率 ， 可 以 使 用 sbt 的 自动 触发 编译 和 运行 过 程 当 保存 
源 代码 文件 的 时 候 。 使 一 个 或 多 个 源 代 码 文 件 修 改 后 可 以 自动 指定 对 应 的 命令 ， 只 需 在 对 应 
命令 前 加 -~ A. 例如 ， 在 交互 模式 下 : 


> ~ compile 
按 回 车 键 定 制 监视 文件 的 改变 


常用 命令 


clean 

删除 所 有 构建 生成 的 文件 (在 target 目 录 中 ) 

compile 

编译 项 目 源 代码 (编译 src/main/scala 和 src/main/java 目录 下 的 源 代码 ) 
test 

编译 并 运行 所 有 的 测试 用 例 

console 

启动 一 个 Scala 语言 交互 模式 ，sbt 在 启动 的 时 候 会 指定 依赖 的 所 有 classpath, 返回 sbt 可 以 
用 :quit `œ ctrl+D (Unix) 和 ctrl+z (Windows) 

run <arguments>* 

运行 项 目 在 虚拟 机 中 


package 


创建 一 个 jar 包 其 中 包含 src/main/resources 和 编译 src/main/scala 或 src/main/java 目 
录 的 class 文件 


help <command> 
显示 指定 命令 的 帮助 信息 ， 如 果 没 有 指定 命令 将 显示 所 有 的 命名 的 摘要 信息 。 
reload 


重新 加 载 配 置 文件 (build.sbt > project/.scala 和 project/.sbt 文件 )， 当 修改 配置 文件 的 时 候 需 
要 执行 


Tab 补 全 


在 交互 模式 下 sbt 支持 Tab 补 全 功能 ， 当 按 一 次 Tab 键 是 sbt 会 显示 所 有 可 能 匹配 的 子 集 命 
令 ， 当 按 多 次 Tab 后 将 显示 多 个 可 能 匹配 的 命令 进行 选择 的 提示 ， 和 Unix tab 补 全 规则 基本 
一 致 


历史 命令 


在 交互 模式 下 可 以 sbt 会 记录 历史 命令 ， 甚 至 是 退出 Sbt 后 重启 历史 命令 还 会 存在 ， 利 用 历史 
命令 简单 的 方法 是 按 " 向 上 键 + 回 车 键 " 调用 上 一 次 执行 的 命令 ， 以 下 是 所 有 执行 的 历史 命令 
调用 方法 : 


显示 历史 命令 的 帮助 信息 


再 次 执行 上 一 个 命令 


执行 index 为 n 的 命令 ，index 为 执行 1: 命令 显示 的 index 
l-n 
执行 第 n 个 命令 的 前 一 个 命令 


!string 


5 


执行 以 'string' 开头 的 最 近 的 命令 
1?string 


执行 包含 string! 字符 串 的 命令 


己 置 文件 .sbt 


.Sbt vs .scala 构建 语句 定义 


一 个 项 目的 构建 定义 可 以 是 在 项 目 根 目录 中 以 sot 后 级 结尾 的 文件 ， 也 可 以 是 一 个 在 子 目 
录 project 下 以 .scala 结尾 的 文件 


这 章 主 要 讨论 .sbt 文件 定义 ， 这 种 定义 已 经 适合 大 部 分 情况 ，.scala 定义 方式 典型 的 用 在 
多 个 .sbt 文件 分 享 共用 的 定义 语句 或 者 是 复杂 的 项 目 构建 中 。 更 多 信息 参考 .scala 定义 
什么 是 构建 语句 ? 

通过 验证 和 解析 构建 语句 文件 ，sbt 以 一 个 不 可 变 Map (key-value 键 值 对 ) 来 描述 构建 过 程 
结束 

例如 ， 一 个 key 为 name 并 且 它 的 Map 和 值 是 字符 串 ， 这 个 配置 项 name 代表 这 个 项 目的 名 称 
构建 语句 定义 不 会 直接 修改 影响 sbt 的 Map 


相反 ， 构 建 语 名 是 一 个 由 setting[T] 类 型 的 对 象 构成 大 的 列表 构成 ，T 是 Setting Map 值 的 类 
型 ，Setting 可 以 通过 ae 添加 一 个 新 的 键 值 对 、 修 改 以 存在 的 key 的 值 (在 
函数 式 编程 中 一 个 不 可 变数 据 结构 和 值 ， 通 过 新 赋值 的 方式 来 修改 值 ， 而 不 是 在 原 值 的 基础 
上 修改 ) 


Æbuild.sbt 中 你 可 能 要 创建 一 个 setting[string] 类 型 的 配置 项 申明 项 目 名 称 : 


name := "hello" 


这 个 Setting[string] 通过 添加 或 替换 原 有 key 值 来 修改 ， 并 且 赋 值 为 "hello" ， 这 个 修改 的 
map 变 成 一 个 新 的 map。 创建 一 个 map，sbt 首先 配置 列表 所 有 修改 的 配置 放 在 一 块 ， 并 且 
如 果 有 的 配置 值 依 赖 某 些 配置 项 将 在 依赖 的 配置 项 后 处 理 。 然 后 sbt 利用 排序 后 的 配置 项 构建 
新 的 map 


总 结 : 构建 语句 是 一 个 setting[T] 组 成 的 列表 ，Setting[T] 是 一 个 可 以 通过 修改 的 map key- 
value 键 值 对 构成 ，T 是 键 值 对 值 的 类 型 
如 何 定义 build.sbt 配置 项 


build.sbt 是 一 个 Seq[Setting[_ ]] ， 是 一 系列 用 空 行 分 割 Scala 表达 式 ， 每 行 是 这 个 序列 的 一 
个 元 素 . 


例如 : 


name := "hello" 
version := "1.0" 


scalaVersion := "2.10.3" 


每 个 配置 项 都 是 一 个 scala À & À > Æ build.sbt 中 的 表达 式 都 是 独立 而 不 是 一 个 scala 代码 
块 . 这 些 表 达 式 由 val、lazy val 和 def 构成 ， 对 象 和 类 不 允许 定义 在 build.sbt 中 ， 应 该 定义 在 
子 目 录 project 中 的 .scala 源 代 码 文件 中 。 


配置 表达 式 的 左 值 如 name , version 和 scalaversion 是 配置 项 的 key, key 是 
SettingKey[T] ，TaskKey[T] 或 Inputkey[T] 的 实例 ， 其 中 十 是 期 望 值 的 类 型 ， 具 体 key 的 类 
型 将 在 下 面 介 绍 。 


Key 对 象 有 一 个 方法 := 调用 将 返回 setting[T] , 你 可 以 用 Java 语法 风格 调用 : 


name. :=("hello") 


在 Scala 中 允许 name := "hello" 方式 调用 (在 Scala 中 对 于 单个 参数 的 方法 允许 这 种 形式 调 
用 ) 


name 的 := 方法 返回 一 个 Setting 对 象 ， 其 中 具体 的 类 型 为 Setting[String], 泛 型 类 型 String 
在 name key 本 身 定 义 中 也 出 现 了 ， 但 是 name 类 型 为 SettingKey[String]. 在 这 个 例子 中 ， 将 
返回 的 Setting[String] 对 象 通过 添加 或 者 替换 得 到 一 个 新 的 sbt 配置 项 map， 并 给 定 值 

为 "hello" 


如 果 给 定 一 个 错误 类 型 的 配置 值 ， 将 无 法 编译 通过 


name := 42 // will not compile 


配置 项 之 间 必 须 用 空 行 分 害 


不 允许 在 budil.sbt 将 配置 写成 如 下 格式 : 


// Will Not compile, not blank lines 
name := "hello" 

version := "1.0" 

scalaVersion := "2.10.3" 


sbt 需要 一 个 分 隔 符 用 来 判断 一 个 表达 式 结束 和 另 一 个 表达 式 起 始 ， .sbt 文件 中 包含 一 系列 
Scala 表达 式 ， 不 是 单个 一 个 Scala 项 目 ， 这 些 表 达 式 必须 分 隔 开 并 且 单 独 进 行 编译 . 


Keys 


e SettingKey[T]: 这 类 key 的 值 只 计算 一 次 ( 当 加 载 项 目的 时 候 计 算 完 成 后 将 一 直 保留 ) 

e TaskKey[T]: 这 类 key 的 值 将 被 作为 任务 调用 ， 可 以 被 重复 调用 计算 的 ， 也 可 能 会 产生 影 
响 

。 InputKey[T]: 这 类 key 是 针对 一 个 任务 需要 传递 一 些 输入 参数 


内 建 Keys 

内 建 Keys 是 调用 对 象 keys 的 成 员 变量 ， 对 于 build.sbt 隐 式 包含 import sbt.Keys. ,所 
以 sbt.Keys.name 可 以 写作 name 

自 定 义 Keys 


自 定义 keys 可 以 分 别 用 settingkey ，taskkey 和 inputkey 方法 创建 . 每 个 方法 定义 期 望 关联 
值 的 类 型 和 该 key 的 描述 信息 ， 每 个 key 的 名 称 保 存在 val 的 常量 中 ， 例 如 ， 定 义 一 个 名 为 
hello 的 任务 类 型 的 key 


lazy val hello = taskKey[Unit]("an example task") 


.Sbt 可 以 包含 vals 和 defs 的 定义 ， 所 有 这 类 型 的 定义 将 在 解析 配置 项 前 执行 ，vals 和 defs 
定义 必须 和 所 有 配置 项 配置 用 空 行 分 割 


注意 : 一 般 情况 下 推荐 用 lazy val 替换 用 val 可 以 避免 初始 化 值得 顺序 问题 


任务 Keys 和 配置 Keys 

TaskKey[T] 被 称 为 一 个 任务 ， 任 务 操作 如 compile À package, 它们 可 能 返回 一 个 Unit 类 型 
(Unit 在 Scala 中 相当 于 void) 或 返回 一 个 关联 的 任务 ， 例 如 package 这 个 任务 将 返回 一 个 
TaskKey[File] 创建 jar 包 的 任务 

当局 动 执 行 一 个 任务 ， 例 如 执行 compile 在 交互 模式 下 ， sbt 将 执行 和 该 任务 相关 的 任务 ， 
sbt 项 目 描 述 表 (map) 中 可 以 保存 一 个 字符 串 的 配置 项 〈 例 如 name 配 置 项 ) ， 也 可 以 是 保 
存 可 执行 的 代码 块 的 任务 (例如 compile 任 务 ) ， 即 使 一 个 可 执行 任务 返回 一 个 字符 串 ， 它 也 
是 在 任何 时 候 可 重复 执行 的 


定义 task 和 settings 


可 以 用 := 给 一 个 配置 项 或 任务 赋值 ， 对 于 配置 项 的 值 将 在 项 目 加 载 的 时 候 一 次 性 计算 ， 对 
于 任务 在 执行 的 时 候 都 会 重新 执行 计算 


例如 : 
// task 
hello := {println("Hello!")} 


// settings 
name := "hello" 


任务 和 配置 项 的 类 型 


Setting 通过 一 个 任务 key 和 一 个 配置 项 key 创 建 出 来 的 有 细微 的 区 别 ， taskkey := 42 结果 是 
Setting[Task[T]] 然而 settingKey := 42 结果 是 Setting[T] . 对 于 大 部 分 情况 下 基本 看 出 
来 区 别 ， 因 为 任务 key 依 然 创 建 一 个 类 型 为 T 的 值 在 任务 执行 的 时 候 

T 和 Task[T] 不 同 的 另 一 个 含义 : 一 个 配置 项 不 能 依赖 一 个 任务 ， 因 为 配置 项 仅 在 项 目 初 始 化 
的 时 候 计 算 一 次 . 


Keys 在 sbt 的 交互 模式 


在 sbt 交 互 模式 下 ， 你 可 以 执行 任何 任务 key, 当 输入 compile 的 时 候 将 执行 任务 key 为 compile 的 
任务 ， 如 果 给 定 的 key 类 型 不 是 任务 而 是 一 个 配置 项 时 将 输出 配置 项 的 值 ， 如果 key 为 任务 类 
型 的 执行 结果 将 不 会 输出 到 终端 ， 要 看 任务 的 输出 结果 需要 执行 show <task name> 而 不 

是 <task name> 。 习 惯性 的 定义 sbt 的 key 的 时 候 使 用 和 Scala 命 名 风格 一 样 的 驼峰 命名 。 


了 解 一 个 key 的 更 多 信息 ， 可 以 在 交互 模式 下 使 用 inspect <keyname> ， 可 以 看 到 该 key 的 值 
的 类 型 和 摘要 描述 信息 等 

在 build.sbt 中 导入 包 

你 可 以 再 build.sbt 顶部 使 用 import 语句 ， 它 们 不 需要 用 空 行 分 割 。Sbt 默认 情况 下 隐 式 的 
导入 了 以 下 包 : 


import sbt._ 
import Process._ 
import Keys._ 


添加 依赖 包 


要 添加 一 个 第 三 方 库 的 依赖 有 两 种 方法 ， 一 种 是 直接 将 jar 包 放 到 lib 目 录 下 ， 另 一 种 方法 是 在 
build.sbt 中 添加 依赖 配置 ， 如 以 下 的 方法 : 


libraryDependencies += "org.apache.derby" % "derby" % "10.4.1.3" 


以 上 这 个 配置 将 在 项 目 中 添加 一 个 Apache Derby 的 库 ， 并 且 版 本 为 10.4.1.3 


libraryDependencies key 包含 两 个 方法 : += (不 是 := ) 和 % ，+= 是 在 原来 值 上 追加 新 值 而 
不 是 替换 原 值 ， 更 多 的 解释 可 参考 配置 配置 项 . % 方法 作用 是 构建 一 个 Ivy 模块 ID 在 依赖 库 中 
被 解析 。 


作用 域 


深入 Keys 


前 面 我 们 一 直 简 单 的 认为 类 似 于 name 的 key 将 一 一 对 应 一 个 值 ， 在 sbt 中 其 实 就 是 一 个 
key-value 的 map 表 ， 事 实 上 每 个 key 除了 关联 一 个 值 外 还 有 一 个 上 下 文 关系 ， 被 称 为 “作用 
域 ” 


例如 : 


e 如 果 在 一 个 项 目 构建 定义 中 含有 多 个 项 目 ， 那 么 一 个 key 可 能 有 不 同 的 值 在 不 同 的 项 目 
中 

e 对 于 项 目 代 码 和 项 目测 试 代码 中 compile 这 个 key 对 应 的 值 是 不 同 的 

© package0ptions (包含 打 包 jar 文 件 的 所 有 参数 ) key 在 打包 class 二 进 制 文件 和 源 代码 
文件 时 的 值 是 不 同 的 


对 于 name 这 个 key 不 是 只 有 一 个 值 ， 值 会 随 作 用 域 的 不 同 而 不 同 ， 但 是 在 同一 个 作用 域 中 一 
个 key 只 有 一 个 值 


以 前 认为 sbt 是 通过 处 理 一 个 配置 列表 生成 key-value 的 一 个 map 表 来 描述 整个 项 目 构建 
的 ， 现 在 可 以 把 这 个 map 认 为 是 一 个 由 作用 域 的 map 表 ， 在 项 目 构建 定义 中 (如 build.sbt 文 件 
中 定义 ) 每 个 key 都 有 一 个 对 应 的 作用 域 。 


一 般 情况 下 每 个 key 都 有 一 个 隐 含 或 默认 的 作用 域 ， 但 是 如 果 上 默认 的 不 是 想 要 的 需要 显 式 窗 
盖 声 明 

作用 域 的 维度 

每 个 作用 域 维度 是 一 个 类 型 ， 每 个 类 型 实例 都 可 以 定义 自己 唯一 值得 key, 以 下 是 三 种 作用 域 
维度 : 


e 项 目 维度 
e 配置 维度 
e。 任务 维度 


作用 域 的 项 目 维度 


如 果 在 一 个 构建 工程 中 定义 多 个 项 目 ， 每 个 项 目 拥有 自己 唯一 的 配置 ， 那 么 这 时 key 的 作用 域 
是 一 个 具有 项 目 维度 的 作用 域 。 


作用 域 项 目 维 度 可 以 设置 为 “整个 工程 有效 (可 以 称 为 该 作用 域 为 工程 作用 域 ) ， 这 样 一 个 配 


置 将 作用 于 整个 构建 工程 中 而 不 是 单一 的 一 个 项 目 ， 构 建 级 别 的 配置 经 常用 来 当做 备用 ， 当 
某 个 项 目 中 没有 配置 该 配置 的 时 候 。 


作用 域 的 配置 维度 


一 个 配置 维度 定义 一 个 构建 类 型 ， 可 能 有 自己 的 classpath 、 源 代码 目录 、 打 包 发 布 等 ， 配 
置 维度 这 个 概念 来 源 于 Ivy, 由 于 Sbt 的 包 依 赖 管理 用 的 是 MavenScopes 


在 sbt 中 的 一 些 配 置 维度 : 


e Compile : 定义 编译 项 目 配置 (src/main/scala) 
e Test: 定义 测试 项 目的 配置 (src/test/scala) 
e Runtime : 定义 运行 一 个 工程 时 的 配置 


默认 情况 下 ， 在 编译 、 打 包 、 运 行 是 所 有 的 key 将 对 应 关联 一 个 配置 维度 ， 所 以 在 不 同 的 配置 
维度 下 运行 结果 可 能 不 同 9 最 常 见 如 任务 类 型 的 key run ， compile , package , 其实 所 有 的 
key 都 会 受 配置 维度 的 作用 域 的 影响 ， 例 如 sourcepirectories , 


scalacOptions , fullClasspath 等 


作用 域 的 任务 维度 


配置 可 以 影响 一 个 任务 的 执行 ， 例 如 ， packagesrc 会 受到 配置 参数 packageoption 的 影响 。 
为 了 实现 这 个 功能 在 sbt 中 packagesrc 可 以 当做 配置 参数 packageoption 的 作用 域 


打包 构建 有 多 个 任务 (packageSrc, packageBin, packageDoc) 可 以 共享 和 打包 相关 的 配置 参 
数 ， 例 如 artifactName 和 packageoptions , 但 是 他 们 的 值 在 不 同 的 任务 维度 下 是 不 同 。 


全 局 作用 域 


每 个 作用 域 维度 都 是 由 一 个 维度 类 型 实例 构成 (例如 任务 维度 就 是 由 一 个 任务 实例 构成 )， 一 
个 维度 也 可 以 由 一 个 全 局 值 构成 


全 局 的 概念 正如 你 所 理解 的 ， 一 个 参数 配置 值 将 被 应 用 到 所 有 的 维度 实例 中 ， 例 如 一 个 任务 
维度 是 全 局 的 ， 那 么 这 个 配置 将 在 所 有 任务 中 有 效 。 
EJE 


当 一 个 作用 域 中 没有 定义 某 个 key 那么 其 在 该 作用 域 是 没有 关联 的 值 。 对 于 每 个 作用 域 ，sbt 
通过 搜索 其 他 作用 域 的 路 劲 作 为 某 个 key 的 备 选 作用 域 ， 典 型 的 例子 : 如 果 一 个 key 在 指定 作 
用 域 中 没有 关联 的 值 ，sbt 试 图 从 其 他 作用 域 获取 一 个 值 ， 例 如 全 局 作用 域 或 者 工程 作用 域 。 


这 个 特性 允许 你 在 一 个 作用 域 中 设置 某 个 key， 在 其 他 的 作用 域 中 继承 该 key, 可 以 使 用 sbt 的 
inspect 命 令 查看 某 个 key 的 搜索 作用 域 详 细 信息 。 


作用 域 在 运行 sbt 时 相关 解释 


在 交互 模式 下 或 命令 下 ， sbt 将 用 下 面 的 形式 表示 作用 域 : 


{<build-uri>}<project-id>/config:intask::Kkey 


®  {<build-uri>}/<project-id> 表示 一 个 项 目 维度 的 作用 域 ? 当 表 示 整 个 工程 的 作用 域 时 
<project-id> 部 分 可 以 省 略 

e config 表示 作用 域 的 配置 维度 

。 intask 表示 作用 域 的 任务 维度 

e key 表示 配置 的 key 


* 在 上 述 任意 段 中 出 现 表 示 在 该 作用 域 维 度 下 是 一 个 全 局 作用 域 
如 果 key 省 略 指定 茶 一 部 分 ， 将 按 以 下 规则 推断 作用 域 : 


@ 如 果 省 略 项 目 维度 将 被 认为 当前 的 项 目 
。 如 果 一 个 依赖 配置 维度 的 key 在 省 略 配置 或 任务 维度 时 将 自动 探测 


作用 域 的 例子 详解 


e *:fullclasspath 指定 一 个 全 局 的 配置 ， 而 不 是 默认 配置 

e doc::fullclasspath 配置 在 doc 任 务 中 fullClasspath 参 数 ， 项 目 和 配置 维度 默认 

e  {file:/home/hp/checkout/hello/}default-aea33a/test:fullClasspath 表示 在 工程 
{file:/home/hp/checkout/hello/} 中 的 项 目 default-aea33a 下 的 配置 维度 为 test 的 
fullClasspath 配 置 参 数 ， 任 务 维度 为 默认 的 

e {file:/home/hp/checkout/hello/}/test:fullclasspath 表示 是 一 个 工程 级 别 的 作用 域 ， 工 
程 为 {ffile:/home/hp/checkout/hello/} 

e {.}/test:fullClasspath 表示 一 个 工程 级 别 的 作用 域 ， 这 块 的 {.}.{.} 在 Scala 代 码 中 
可 以 写成 ThisBuild 

e {file:/home/hp/checkout/hello/}/compile:doc::fullClasspath 表示 fullClasspath 配置 参 


数 设置 所 有 的 作用 域 维度 


令 测 作用 域 
在 Sbt 交互 模式 下 可 以 使 用 命令 inspect 来 检测 一 个 配置 参数 的 作用 ， 例 如 


> inspect test:fullClasspath 


命令 执行 返回 结果 如 下 : 


[info] Task: scala.collection.Seq[sbt.Attributed[java.io.File]] 
[info] Description: 

[info] The exported classpath, consisting of build products and unmanaged and managed 
, internal and external dependencies. 
[info] Provided by: 

[info] f{file:/home/hp/checkout/hello/}default-aea33a/test:fullClasspath 
[info] Dependencies: 

[info] test:exportedProducts 

[info] test:dependencyClasspath 
[info] Reverse dependencies: 

[info] test:runMain 

[info] test:run 

[info] test:testLoader 

[info] test:console 

[info] Delegates: 

[info] test:fullClasspath 

[info] runtime:fullClasspath 

[info] compile:fullClasspath 

[info] *:fullClasspath 

[info] {.}/test:fullClasspath 

[info] £{.}/runtime:fullClasspath 
[info] £{.}/compile:fullClasspath 
[info] {.}/*:fullClasspath 

[info] */test:fullClasspath 

[info] */runtime:fullClasspath 

[info] */compile:fullClasspath 

[info] */*:fullClasspath 

[info] Related: 

[info] compile:fullClasspath 

[info] compile:fullClasspath(for doc) 
[info] test:fullClasspath(for doc) 
[info] runtime:fullClasspath 


在 第 一 行 中 可 以 看 到 一 个 任务 key, 其 值得 类 型 是 
scala.collection.Seq[sbt.Attributed[java.io.File]]. 


"Provided by" 表示 该 配置 参数 定义 的 作用 域 : 

{file:/home/hp/checkout/hello/}default-aea33a/test:fullclasspath (fullClasspath 配置 在 作 
用 域 任务 维度 为 test， 作 用 域 项 目 维度 为 人 le:/home/hp/checkouthello/}jdefaultraea33a 的 作用 
城中 ) 


"Dependencies": 配置 参数 章节 解释 
"Delegates": 表示 如 果 某 个 key 没 有 定义 ， 将 按照 以 下 路 劲 搜索 : 


e 两 个 配置 作用 域 ( runtime:fullClasspath ， compile:fullClasspath ) ? 在 这 些 作用 域 中 
的 key， 项 目 维度 没有 指定 默认 是 当前 项 目 ， 任 务 维度 没有 指定 默认 是 任务 全 局 作用 域 

e 配置 维度 为 全 局 的 作用 域 ( *:fullclasspath ) ， 项 目 维 度 没 有 指定 默认 是 当前 项 目 ， 任 
务 维度 没有 指定 默认 是 任务 全 局 作用 域 

。 项 目 维 度 设置 {.} 或 者 ThisBuild (表示 工程 级 别 的 作用 域 ， 没 有 指 定 项 目 ) 

e 项 目 维度 设 置 为 全 局 作用 域 ( */test:fullClasspath )( 注 总 意 ; 当 没 有 指定 项 目的 时 候 表 示 当 
前 项 目 ， 这 块 代表 的 意思 是 全 局 作用 域 ， 比 如 */test:fullclasspath 和 
test:fullClasspath 代表 的 意义 不 一 样 ) 

e 项 目 和 配置 维度 都 为 全 局 的 作用 域 ( */*:fullclasspath ), 任务 维度 没有 指定 ， 所 以 当 设 
定 为 */*:fullClasspath 作用 域 时 2 在 作用 域 的 三 个 维度 上 都 为 全 局 的 


度 设 
Zi 


运行 inspect fullClasspath (对 比 上 一 个 例子 inspect test:fullClasspath ) 会 发 现 返 回 的 
结果 有 所 不 同 ， 这 是 因为 当 不 指定 配置 维度 的 作用 域 时 ，Sbt 将 inspect fullClasspath 自动 探 
测 为 compile.inspect compile:fullClasspath 执行 . 


如 何在 工程 构建 中 定义 作用 域 


如 果 单 独 在 build.sbt 中 创建 一 个 key， 这 个 key 作 用 域 的 项 目 维度 将 为 当前 项 目 ， 配 置 和 任务 维 
度 将 为 全 局 作用 域 : 


name := "hello" 


运行 命令 inspect name 将 看 到 "Provided 

by" 为 : {file:/home/hp/checkout/hello/}default-aea33a/*:name ， 表 示 作 用 域 项 目 维度 为 
{file:/home/hp/checkout/hello/}default-aeas3a , 作用 域 任务 维度 为 * (全 局 ) ， 作 用 域 任务 
维度 没有 指定 默认 代表 全 局 , build.sbt 定义 是 针对 单个 项 目的 ， 所 以 “当前 项 目 ” 指 的 就 是 当前 

build.sbt 定 义 的 项 目 (对 于 多 项 目 构建 ,每 个 项 目 有 对 应 一 个 build.sbt) 


ey 来 设 定 作 用 域 ， 其 参数 可 以 为 作用 域 的 任何 一 个 维度 的 对 象 实例 。 
例如 ， 可 以 通过 如 下 方式 将 name 配置 设置 为 配置 维度 为 Compile 的 作用 域 : 


name in Compile := "hello" 


或 者 可 以 将 name 配置 设置 为 任务 维度 为 packageBin 的 作用 域 (当然 这 例子 有 点 不 合适 ) 


name in packageBin := "hello" 


当然 了 也 可 以 为 一 个 key 指 定 多 个 作用 域 维度 ,例如 将 key name 同时 指定 配置 维度 和 任务 维 
度 : 


name in (Compile, packageBin) := "hello" 


也 可 以 指定 一 个 key 的 作用 域 为 全 局 : 


name in Global := "hello" 


( name in Global 隐 式 将 作用 域 转化 为 一 个 对 于 所 有 维度 都 为 全 局 的 作用 域 ， 默 认 情 况 下 任务 
和 配置 维度 的 作用 域 已 经 是 全 局 的 了 ， 但 是 这 块 会 影响 项 目 维度 的 作用 ， 因 为 其 隐 式 转化 
为 */*iname 而 不 是 {file:/home/hp/checkout/hello/}default-aea33a/*:name ) 


如 果 没 有 用 过 Scala 语 言 ， 理解 in 和 := 这 两 个 方法 很 重要 ， 推 荐 用 scala 语 法 形式 配置 ， 
但 是 也 可 以 用 Java 语 法 形式 配置 : 


name.in(Compile).:=("hello") 


什么 时 候 指定 作用 域 


当 定义 一 个 key 在 默认 作用 域 下 会 有 问题 时 需要 指定 作用 域 ， 例 如 compile 任务 类 型 的 配置 ， 
默认 作用 域 是 在 compile 或 Test 配置 维度 下 ， 不 会 存在 于 其 他 作用 域 中 。 


如 果 修 改 compile 这 个 任务 配置 的 值 需要 指定 其 作用 域 ， 修 改 语 句 
如 compile in Compile 或 compile in Test ,如果 单独 写作 为 compile Sbt 会 重新 创建 一 个 作 
用 域 为 当前 项 目的 任务 配置 ， 而 不 是 去 修改 在 配置 维度 作用 域 下 的 标准 compile 任 务 配置 。 


如 果 得 到 一 个 错误 信息 “Reference to undefined setting”， 一 般 情 况 下 是 因为 配置 项 指定 作用 
域 失 败 或 者 指定 了 一 个 错误 的 作用 域 。 当 定义 的 key 可 能 在 其 他 作用 域 中 已 经 定义 会 接收 
到 “Did you mean compile:compile?” 错 误 提 示 信 息 


一 般 会 简单 的 认为 配置 项 就 是 一 个 key-value 键 值 对 ， 其 实 对 于 所 有 的 配置 项 都 会 包含 一 个 
key-value 和 一 个 对 应 的 作用 域 (作用 域 有 三 个 维度 ) ， 如 配置 表达 

式 : packageOptions in (Compile, packageBin) , 当 配 置 为 packageOptions 也 是 一 个 合法 的 配 
置 项 ， 只 是 该 配置 项 的 作用 域 将 是 默认 的 作用 域 (项 目 维度 为 当前 项 目 ， 任 务 和 配置 维度 为 全 
局 ) 


置 参 数 的 方法 


回顾 : 配置 项 


一 个 工程 构建 定义 一 个 setting 类 型 的 列表 ， 通 过 Sbt 转 化 为 sbt 的 描述 数据 结构 (key-value 
键 值 对 ) ，Setting 作 为 一 个 转化 前 的 输入 类 型 ， 转 化 后 输出 一 个 map 表 。 


不 同 的 配置 项 有 不 同 的 转化 方法 ， 例 如 前 面 的 := 方法 。 一 个 Setting 类 型 的 配置 项 可 以 通 
过 := 转化 成 一 个 值 为 一 个 常量 的 map 表 ， 例 如 ， 转 化 一 个 配置 项 name := "hello" 是 将 
hello 赋值 给 该 配置 项 的 key 


Settings must end up in the master list of settings to do any good (all lines in a build.sbt 
automatically end up in the list, but in a .scala file you can get it wrong by creating a Setting 
without putting it where sbt will find it). 


忆 置 值 追 加 操作 : += 和 ++= 


十 直接 赋值 方法 := 是 最 简单 的 一 种 转化 方法 ， 所 有 的 配置 项 还 有 其 他 的 方法 ， 在 
Settingkey[T] 中 泛 型 T 如 果 是 一 个 序列 类 型 的 话 ， 支 持 追 加 操作 不 仅仅 是 重新 赋值 替换 操 
作 。 


e。 += 操作 是 追加 单个 元 素 到 序列 中 
o ++= 操作 是 追加 一 个 序列 到 序列 中 


比如 , 对 于 配置 、sourceDirectories in Compile 值得 类 型 是 seq[File] ,默认 情况 下 这 个 配置 
已 经 有 包含 了 目录 src/main/scala 。 如 果 还 想 编译 目录 source 下 的 源 代码 可 以 添加 该 目录 : 


sourceDirectories in Compile += new File('"source") 


或 者 ， 利 用 sbt 包 中 提供 的 函数 file() 更 加 方便 


sourceDirectories in Compile += file("source") 


file() 函数 也 是 创建 File 对 象 
也 可 以 用 操作 符 ++= 一 次 性 添加 多 个 目录 : 
sourceDirectories in Compile ++= Seq(file("sources1"), file('"sources2")) 


À Ÿ Seq(a, b, c, ...) 是 Scala 的 标准 语法 ， 用 来 创建 一 个 序列 


当然 了 除了 追加 操作 还 支持 直接 赋值 替换 配置 原 值 : 


sourceDirectories in Compile := Seq(file("sources1"), file('"sources2")) 


其 他 配置 项 计算 一 个 配置 项 
引用 其 他 的 任务 配置 或 参数 配置 的 值 通过 调用 任务 或 参数 配置 ， 通 过 方法 := 、+= 或 ++= 来 
引用 一 个 配置 


比如 ， 定 义 一 个 项 目 组 织 和 项 目 名 称 一 样 的 配置 


// organization 接收 的 值 类 型 和 name 一 样 都 是 Setting[String] 
organization := name.value 


或 者 通过 引用 项 目 目录 来 定义 项 目 名 称 : 


// name 是 Key[String] 类 型 ，baseDirectory 是 Key[File] 
name := baseDirectory.value.getName 


由 于 baseDirectory 的 值 类 型 和 name 的 值 类 型 不 一 样 ， 需 要 调用 java 的 java.io.File 类 库 
getName 方法 转化 


Sbt 同 时 支持 引用 多 个 配置 项 的 值 ， 例如: 


name := "project " + name.value + " from " + organization.value + " version " + versio 
n.value 


参数 配置 依赖 


在 配置 name := baseDirectory.value.getName 中 ， 参 数 配置 name 依赖 配置 baseDirectory > 
如 果 在 放 有 上 述 配 置 的 build.sbt 的 目录 下 交互 模式 运行 inspect name 命令 ， 将 返回 如 下 的 提 
示 信 息 : 


[info] Dependencies: 
[info] *:baseDirectory 


sbt 是 很 容易 的 探测 出 各 个 参数 配置 间 的 依赖 关系 的 ， 包 括 任务 配置 也 可 以 依赖 参数 配置 ， 或 
者 任务 配置 间 相 互 依赖 ， 例 如 运行 inspect compile 会 发 现 compile 任务 配置 会 依赖 参数 配 

置 compilelnputs > inspect compileInputs 还 会 发 现 参数 配置 compilelnputs 又 依赖 其 他 的 参 

数 配 置 ， 等 等 。 最 后 会 发 现形 成 一 个 依赖 链 ， 这 些 依赖 关系 是 在 sbt 编 译 的 时 候 自动 探测 计算 
的 。 所 以 所 有 的 依赖 关系 都 是 自动 计算 的 ， 不 需要 显示 的 声明 。 


未 定义 配置 


当 用 := 、+= 或 ++= 方法 去 引用 一 个 配置 ， 所 依赖 的 配置 必须 存在 ， 否 则 sbt 会 报错 误 信 
息 "Reference to undefined setting", 如 果 报 错 需要 确认 依赖 的 配置 是 否 在 指定 作用 域 中 存在 。 


也 可 能 会 出 现 循环 依赖 的 配置 错误 ， 这 个 时 候 sbt 会 提示 错误 


任务 配置 引用 参数 配置 


一 个 任务 配置 可 以 依赖 参数 配置 或 其 他 的 任务 配置 ， 通 过 def.task 或 操作 符 
(:=、+= 或 +t= ) 引 用 配置 


比如 ， 一 个 源 代码 生成 任务 将 依赖 项 目 根 目录 和 编译 classpath 两 个 参数 配置 


sourceGenerators in Compile += Def.task { 
myGenerator(baseDirectory.value, (managedClasspath in Compile).value) 
}.taskValue 


任务 配置 依赖 


如 配置 文件 .sbt 所 述 ， 一 个 任务 配置 用 赋值 方法 := 操作 的 参数 是 setting[Task[T]] 而 不 
是 setting[T] 等 ， 任 务 配置 输入 参数 可 以 接收 一 个 参数 配置 作为 输入 ， 但 是 一 个 参数 配置 是 
不 可 以 接收 一 个 任务 配置 作为 输入 


以 下 为 两 个 配置 


val scalacOptions = taskKey[Seq[String]]("Options for the Scala compiler.") 
val checksums = settingKey[Seq[String]]("The list of checksums to generate and to veri 
fy for dependencies."") 


(scalacOptions 和 checksums 之 间 没 有 任何 联系 ， 它 们 只 是 配置 值得 类 型 相同 ， 但 是 其 中 
scalacOptions 是 一 个 任务 配置 ) 


在 build.sbt 中 允许 一 个 任务 配置 依赖 参数 配置 ， 比 如 : 


/ 合法 的 配置 
scalacOptions := checksums.value 


是 合法 的 配置 方法 ， 但 是 如 果 将 一 个 参数 配置 配置 成 依赖 一 个 任务 配置 的 时 候 就 会 报错 ， 因 
为 参数 配置 在 项 目 加 载 的 时 候 只 计算 一 次 ， 可 以 当做 常量 处 理 ， 但 是 任务 配置 是 在 不 断 的 重 
复 的 运行 的 。 


// 非法 的 配置 
checksums := scalacOptions.value 


追加 依赖 操作 : += 和 ++= 
一 些 配置 可 以 被 追加 引用 到 一 个 已 经 存在 的 配置 中 ， 和 直接 赋值 操作 := 一 样 . 


例如 ， 有 一 个 项 目 履 盖 率 报告 文件 (文件 名 引用 项 目 名 称 的 参数 配置 ) 需要 删除 ， 可 以 通过 
如 下 配置 


cleanFiles += file('"coverage-report-" + name.value + ".txt") 


Lib 库 依赖 


添加 Lib 库 依赖 关系 有 两 种 方式 : 


eo 非 管 理 依赖 方式 ， 是 通过 将 依赖 的 Jar 包 放 到 项 目的 lib 目 录 
o 管理 依赖 方式 ， 是 在 工程 构建 配置 中 配置 依赖 关系 ，sbt 会 自动 从 托管 代码 库 中 下 载 依赖 
库 


非 管 理 依赖 方式 


很 多 人 用 管理 依赖 的 方式 替代 非 管理 方式 ， 其 实 非 管 理 方式 用 起 来 非常 方便 。 非 管理 依赖 方 
式 的 工作 原理 就 是 将 jar 包 放 到 lib 目 录 下 ，sbt 会 自动 的 将 其 添加 到 classpath 中 。 也 可 以 将 一 些 
测试 依赖 放 到 lib 目 录 下 ， 如 ScalaCheck、Specs2 和 ScalaTest 这 些 依赖 包 


A he Cae ed 终端 ) ， 如 果 想 
修改 某 个 配置 维度 的 作用 域 的 classpath 配 置 ， 需 要 按照 如 下 修改 方 


式 dependencyClasspath in Compile À dependencyClasspath in Runtime 


对 于 非 管理 方式 的 依赖 不 需要 在 build.sbt 额 外 配置 ， 但 是 如 果 想 自 定义 一 个 依赖 目录 而 不 是 默 
认 的 lib 目 录 时 ， 可 以 通过 修改 unmanagedBase 参数 配置 ， 比如 用 目录 custom lib 替换 lib 目录 


unmanagedBase := baseDirectory.value / "custom lib" 
其 中 baseDirectory 是 项 目的 根 上 目录， 修改 unmanagedBase 参数 配置 依赖 baseDirectory ,关于 
参数 配置 的 依赖 可 以 参考 配置 参数 的 方法 


在 非 管 理 依赖 方式 中 还 提供 了 一 个 任务 配置 unmanagedJars 用 来 列举 unmanagedBase 所 有 的 jar 
包 的 ， 在 多 项 目 构建 中 或 更 加 复杂 的 构建 中 可 能 需要 修改 unmanagedJars 配置 来 完成 。 例 如 ， 
在 Compile 这 个 配置 维度 作用 域 下 要 清空 所 有 非 管理 方式 的 jar 包 ， 可 以 利用 如 下 配置 


unmanagedJars in Compile := Seq.empty[sbt.Attributed[java.io.File]] 


管理 依赖 方式 


sbt 利用 Apache lvy 方 式 管理 依赖 包 ， 如 果 熟 悉 Ivy 或 Maven 的 话 ， 理 解 sbt 的 管理 依赖 包 将 
会 非常 的 容易 。 
libraryDependencies 参数 配置 


一 般 情 况 下 只 需要 通过 配置 libraryDependencies 参数 配置 即 可 设置 依赖 的 包 ， 也 可 以 通过 编 
写 maven 的 POM 配 置 文件 或 Ivy 的 配置 文件 来 扩展 包 依 赖 的 功能 。 


以 下 是 申明 一 个 包 依 赖 关 系 ， 其 中 groupId ， artifactId 和 revision 是 字符 串 类 型 


libraryDependencies += groupID % artifactID % revision 


或 用 如 下 申明 ， 其 中 configuration 是 一 个 字符 串 或 者 一 个 配置 维度 实例 


libraryDependencies += groupID % artifactID % revision % configuration 


libraryDependencies 这 个 配置 key 在 Keys 中 声明 语句 如 下 


val libraryDependencies = settingKey[Seq[ModuleID]]("Declares managed dependencies.") 


ME libraryDependencies key 申明 语句 中 可 以 看 出 其 值 是 接收 一 个 由 ModulelD 对 象 构成 的 
序列 。 在 申明 依赖 关系 的 语句 中 有 % 方法 ， 该 方法 是 用 字符 串 创建 一 个 ModulelD 类 型 的 对 
Zo 

当然 sbt 必 须知 道 所 配置 的 依赖 库 到 什么 地 方 下 载 ， 如 果 配 置 的 依赖 库 在 默认 的 远程 库 中 存在 
将 直接 下 载 ， 比 如 Apache Derby 就 是 在 标准 远程 库 Maven2 中 : 


libraryDependencies += "org.apache.derby" % "derby" % "10.4.1.3" 


如 果 配 置 到 build.sbt 并 且 执 行 update ， sbt 将 自动 将 其 下 载 
到 —/.ivy2/cache/org.apache.derby/ A 录 下 (由 于 compile 任务 配置 会 依赖 update 这 个 任务 ， 
所 以 一 般 情 况 不 用 手动 执行 Update) 


当然 ， 也 可 以 用 ++= 方法 一 次 性 添加 一 个 依赖 列表 : 


libraryDependencies ++= Sed( 
groupID % artifactID % revision, 
groupID % otherID % otherRevision 


) 
在 少数 情况 下 可 能 也 会 用 到 := 赋值 方法 


指定 依赖 库 Scala 版 本 


ke À A] groupID %% artifactID % revision 而 不 是 groupID % artifactID % revision 方式 配置 
依赖 关系 别 在 于 前 者 的 groupld 后 的 是 两 个 % )，sbt 将 会 添加 当前 scala 版 本 到 依赖 的 
报名 后 ， 这 个 只 是 一 个 快捷 的 方式 ， 你 也 可 以 直接 硬 编码 scala 版 本 : 


libraryDependencies += "org.scala-tools" % "scala-stm 2.11.1" % "0.3" 


假如 当前 构建 项 目的 scalaVersion 为 2.11.1, 如 下 方式 和 上 述 的 结果 是 一 样 (也 JA g% 方式 添加 
依赖 库 的 Scala 版 本 ) 


libraryDependencies += "org.scala-tools" %% "scala-stm" % "0.3" 


在 多 个 Scala 版 本 下 构建 项 目 ， 可 以 使 用 这 种 方法 来 匹配 二 进 制 兼容 的 对 应 依赖 包 


复杂 的 情况 是 经 常 有 依赖 包 对 于 不 同 的 Scala 版 本 间 有 细微 的 差别 ， 所 以 如 果 依赖 包 
在 2.10.1 版 本 下 存在 ， 但 是 当前 项 目 scalaVersion := "2.10.4", 将 会 发 现 用 ww% 是 获取 不 到 依 
赖 包 的 ， 这 时 需要 确定 该 版 本 的 依赖 包 是 否 可 用 ， 并 且 可 以 通过 硬 编码 版 本 的 方式 添加 依赖 


Ivy 自动 匹配 版 本 


在 配置 groupID % artifactID % revision 中 revision 不 是 一 定 要 指定 一 个 固定 的 版 本 号 ? Ivy 
可 以 自动 选择 一 个 高 版 本 包 根 据 指定 的 限定 条 件 ， 例 如 如 果 要 替换 一 个 固定 版 本 "1.6.1"， 可 以 
通过 指定 "latest.integration'","2.9.+" 或 "[1.0,)" 来 替换 ， 更 多 的 配置 请 参看 |vy 配 置 文档 


远程 依赖 库 地 址 管理 


不 是 所 有 的 包 在 同一 个 远程 库 中 都 存在 ，sbt 默 认 用 的 是 标准 的 Maven2 远程 库 ， 如 果 依 赖 的 包 
不 在 默认 的 远程 库 中 ， 需 要 手动 指定 一 个 远程 库 供 |vy 查 找 。 


添加 远程 库 的 方法 如 下 : 
resolvers += name at location 
例如 : 


resolvers += "Sonatype OSS Snapshots" at "https://oss.sonatype.org/content/repositorie 
s/snapshots" 


resolvers 这 个 配置 项 在 keys 中 的 定义 如 下 : 


val resolvers = settingKey[Seq[Resolver]]("The user-defined additional resolvers for a 
utomatically managed dependencies.") 


在 添加 远 元 程 库 配 置 语句 中 的 at 方法 是 将 字符 串 转化 为 Resolver FA o 


sbt 也 支持 搜索 本 地 的 maven 依赖 库 ， 配 置 如 下 : 


resolvers += "Local Maven Repository" at "file://"+Path.userHome.absolutePath+"/.m2/re 
pository" 


也 可 以 简写 为 : 


resolvers += Resolver.mavenLocal 


重 写 默认 的 远程 依赖 库 


参数 配置 resolvers 中 是 不 包含 默认 的 远程 库 配 置 的 ， 仅 仅 用 来 配置 添加 远程 库 地 址 ，sbt 最 
终 是 通过 合并 resolvers 配置 和 externalResolvers 配置 来 得 到 远程 库 地 址 集合 ， 所 以 如 果 要 
修改 默认 远程 库 的 话 需 要 修改 参数 配置 externalResolvers 


配置 维度 的 作用 域 依 赖 库 


经 常 在 测试 代码 中 会 用 到 依赖 库 (在 src/test/scala 目 录 中 的 代码 将 通过 配置 维度 为 Test 作 用 域 
的 配置 来 编译 ) 但 在 项 目 代 码 中 不 会 用 到 。 


如 果 只 想 在 编译 测 a 的 时 候 加 入 到 classpath 而 在 编译 项 目 代码 的 时 候 不 加 入 ， 可 以 通过 
添加 % "test" 指 定 配置 维度 的 作用 域 来 限定 : 


libraryDependencies += "org.apache.derby" % "derby" % "10.4.1.3" % "test" 
也 可 以 指定 配置 维度 的 一 个 实例 对 象 来 限定 : 


libraryDependencies += "org.apache.derby" % "derby" % "10.4.1.3" % Test 


那么 ， 当 限定 到 某 个 配置 维度 域 时 利用 命令 show compile:dependencyClasspath 查看 配置 
时 将 不 会 看 到 derby jar 包 ， 但 


包 在 列表 中 。 


作用 
是 如 果 查 看 show test:dependencyClasspath 将 会 看 到 derby jar 


见 的 ， 测 试 相 关 的 包 ScalaCheck、Specs2 和 ScalaTest 将 指定 % "test" 来 限定 在 Test 配 置 维 
下 


党 
度 下 使 用 。 


通常 在 一 个 工程 中 构建 多 个 项 目 间 会 有 关联 ， 尤 其 是 它们 都 依赖 一 个 项 目 时 可 以 很 容易 的 更 
新 项 目 


在 一 个 工程 中 每 个 子 项 目 都 会 有 自己 的 源 代码 目录 、 生 成 各 自 的 jar 包 当 执 行 package 时 . 
一 个 项 目 通 过 申明 一 个 project 类 型 的 懒 值 来 定义 ， 例 如 : 


lazy val util = project 


lazy val core = project 


这 个 变量 值 名 称 将 被 用 来 当做 Project Id 和 项 目的 根 目 录 名 称 ， 这 个 ID 将 用 来 在 命 军令 令 行 中 
引用 项 目 ， 利 用 方法 in 可 以 修改 默认 的 项 目 根 目录 。 例 如 ， 以 下 是 更 加 明确 的 申明 项 目 : 


lazy val util = project.in(file("util")) 


lazy val core = project in file("core") 


项 目 间 依 赖 


在 一 个 工程 中 一 个 项 目 完全 可 能 依赖 另 一 个 项 目 ， 经 常 有 两 种 依赖 方式 : 聚合 和 classpath 


目 
聚合 的 意思 是 当 运 行 一 个 任务 在 一 个 项 目 中 ， 过 聚合 方式 依赖 的 项 目 也 会 执行 ， 例 如 : 
lazy val root = (project in file(".")). 

aggregate(util, core) 
lazy val util = project 


lazy val core = project 


在 上 面 的 例子 中 ， root 项 目 聚 合 了 项 目 util 和 core ， 编 译 root 项 目 将 看 到 三 个 项 目 被 编 
译 。 

在 项 目 聚 合 过程 中 ， 以 root 项 目 为 例 ， 是 可 以 控制 任 度 作 用 域 的 配置 的 ， 例 如 ,可 以 控 
制 在 执行 update 这 个 任务 时 不 进行 聚合 : 


lazy val root = (project in file(".")). 
aggregate(util, core). 
settings( 
aggregate in update := false 


) 


aggregate in update 表示 在 update 这 个 任务 维度 作用 域 中 aggregate 的 配置 2 (有 具体 可 参考 
作用 域 章节 ) 


注意 : 在 聚合 过 程 中 聚合 是 并 行 处 理 的 ， 所 以 被 聚合 的 项 目 时 没有 先后 顺序 的 


classpath 依赖 
在 源 代 码 层 级 一 个 项 目 可 能 会 依赖 另 一 个 项 目 ， 可 以 通过 dependson 方法 添加 依赖 关系 ， 例 
如 ， core 项 目 需 要 在 classpath 中 指定 util 项 目 ， 可 以 这 样 定义 core MA: 


lazy val core = project.dependsOn(util) 


这 样 就 可 以 在 core 项 目 中 调用 util 项 目的 方法 ， 当 编译 的 时 候 会 有 编译 顺序 ， util 必须 
在 core 之 前 编译 ， 如 果 依 赖 多 个 项 目 ， 可 以 给 dependson 方法 指定 多 个 参数 ， 例 
如 ， dependsOn(bar, baz) 

维度 作用 域 的 classpath 依赖 


foo dependson(bar) 表示 foo 在 compile 这 个 配置 维度 作用 域 下 依赖 在 配置 维度 作用 域 
À compile 下 的 bar 项 目 ， 确 切 的 写法 应 该 为 : dependson(bar % "compile->compile") , 
在 "compile->compile" 中 的 -> 表示 项 目 间 的 依赖 关系 ， 所 以 "test->compile" 可 以 表示 为 
在 Test 配置 维度 作用 域 下 的 foo 依 赖 compile 配置 维度 作用 域 下 的 bar 


->config" 这 部 分 隐 含 意思 为 "->compile", 所 以 dependson(bar % "test") 意思 是 在 Test 配 
度 作 用 域 下 的 foo 依 赖 compile 配置 维度 作用 域 下 的 bar 


可 以 声明 为 "test->test"， 意 思 为 在 Test 配置 维度 作用 域 下 项 目 依赖 ， 例 如 
在 src/test/scala À 录 的 公共 类 库 可 以 在 src/test/scala 源 代 码 中 使 用 。 


针对 一 个 依赖 关系 可 以 配置 多 个 配置 维度 的 作用 域 ， 用 分 号 分 隔 ， 例 


如 : dependson(bar % "test->test;compile->compile") 


默认 根 项 目 


如 果 一 个 项 目 没 有 在 工程 根 目 录 下 定义 ，sbt 将 创建 一 个 聚合 整个 工程 子 项 目的 默认 项 目 。 


由 于 项 目 hello-foo 定义 了 base = file("foo") ,项 目 目录 为 子 目 录 foo， 源 代码 可 以 直接 放 到 
foo 目 录 中 ， 类 似 foo/Foo.scala 或 放 到 src/main/scala ,如 果 是 采用 sbt 工 程 构建 标准 目录 ， 
foo 目 录 下 还 包括 工程 构建 定义 文件 。 


在 foo 目 录 下 的 任何 .sbt 文件 将 被 合并 在 一 起 ， 并 且 定 义 的 配置 项 属于 项 目 维 
度 hello-foo 作用 域 S: 


在 hello 工 程 中 允许 子 项 目 配置 不 同 的 版 本 ， 可 以 在 配置 文 
件 : hello/build.sbt, hello/foo/build.sbt, #hello/bar/build.sbt 中 配置 不 同 版 本 ， 现 在 在 交 
互 模式 下 执行 show version 将 看 到 如 下 信息 : 


> show version 

[info] hello-foo/*:version 
[info] 0.7 

[info] hello-bar/*:version 
[info] 0.9 

[info] hello/*:version 
[info] 0.5 


hello-foo/*:version 被 定义 在 hello/foo/build.sbt 中 hello-bar/*:version 被 定义 
在 hello/bar/build.sbt 中 hello/*:version 被 定义 在 hello/build.sbt 中 


每 个 version 是 不 同 的 项 目 维度 作用 域 ， 但 是 这 三 个 build.sbt 部 分 配置 是 相同 的 


每 个 项 目的 配置 都 在 自己 项 目 目录 下 的 sbt 文件 中 配置 ， 其 实 对 于 上 述 配置 有 更 简单 的 
方法 ， 那 就 是 配置 到 scala 文件 中 ， 列 举 出 项 目 和 对 应 的 项 目 根 目录 


你 会 发 现 将 多 个 项 目 按 顺序 定义 在 .scala 配置 文件 中 会 比 单独 定义 在 各 自 的 目录 下 更 加 清 
晰 > 不 过 这 个 自 己 决 定 S 


不 允许 定义 一 个 子 目录 为 project 的 目录 ， foo/project/Build.scala 将 会 被 忽略 


交互 模式 下 操作 项 目 


nn 使 用 命令 projects 列举 出 该 工程 的 所 有 项 目 ， 命 
令 project <projectname> ere 前 项 目 。 当 运行 一 个 任务 的 时 候 (比如 compile ) 将 在 
当前 项 目下 运行 ， 所 以 没有 必要 在 急 项 目 中 编译 ， 可 以 单独 纺 译 一 个 于 项目。 


置 代码 复 用 


.Sbt 配置 文件 中 的 定义 在 多 个 .sbt 中 是 相互 不 可 见 的 ， 为 了 是 多 个 .sbt 间 复 用 配置 ， 可 以 在 根 
目录 的 project 目 录 下 定义 一 个 或 多 个 .scala 的 文件 ， 这 个 目录 其 实 也 是 一 个 sbt 工 程 ， 只 不 过 
这 个 的 作用 是 工程 构建 。 


例如 : 


<root>/project/Common. scala: 


import sbt._ 
import Keys._ 


object Common { 
def text = "org.example" 
} 


在 .Sbt 中 可 以 直接 调用 : 


<root>/build.sbt: 


organization := Common.text 


插件 使 用 
什么 是 插件 ? 


插件 可 以 扩展 工程 构建 定义 ， 是 增加 一 些 新 的 配置 ， 配 置 可 以 是 任务 配置 ， 例 如 ， 一 个 
插件 可 以 增加 一 个 codecoverage a ， 用 来 生成 项 目 单 元 测试 的 代码 履 盖 率 报告 。 


使 用 插件 


如 果 一 个 项 目的 目录 为 hello, 并 且 在 该 项 目 中 使 用 sbt-site 这 个 插件 ， 只 需 创 建 一 个 名 
为 hello/project/site.sbt 配置 文件 ， 并 且 通 过 addsbtPlugin 方法 申明 该 插件 的 |vy 模 块 ID : 


addSbtPlugin('"com.typesafe.sbt" % "sbt-site" % "0.7.0") 


如 果 添 加 一 个 sbt-assembly 的 插件 ， 创建 一 个 hello/project/assembly.sbt 配置 文件 ， 并 且 
配置 如 下 : 


addSbtPlugin("com.eed3si9n" % "sbt-assembly" % "0.11.2") 


并 不 是 每 个 插件 在 默认 的 远程 库 中 都 存在 ， 这 个 需要 根据 具体 的 插件 文档 来 配置 远程 库 地 
dE : 


resolvers += Resolver.sonatypeRepo("public") 
插件 一 般 都 会 提供 一 些 配置 来 添加 启用 插件 ， 下 一 小 节 讨 论 这 个 问题 。 


插件 的 启用 


一 个 插件 通过 配置 可 以 自动 的 添加 到 项 目 中 ， 不 需要 额外 的 做 任何 工作 ， 在 0.13.5 有 一 个 新 的 
- a 以 自动 启用 和 配置 在 一 个 项 目 中 ， 大 部 分 自动 插件 都 已 经 自动 的 进行 了 默认 的 配 
过 有 个 别 的 插件 也 需要 明确 启用 。 


如 果 一 个 插件 需要 配置 启用 才 可 以 使 用 ， 需 要 在 build.sbt 中 进行 如 下 配置 : 


lazy val util = (project in file("util")). 
enablePlugins(FooPlugin, BarPlugin). 
settings( 
name := "hello-util" 


) 


enablePlugins 方法 用 来 指定 需要 启用 的 配置 。 


一 个 项 目 也 可 以 通过 disableplugins 来 排除 使 用 一 个 插件 。 例 如 ， 在 util 项 目 中 不 想 用 插 
件 IvyPlugin ， 可 以 如 下 配置 : 


lazy val util = (project in file("util")). 
enablePlugins(FooPlugin, BarPlugin). 
disablePlugins(plugins.IvyPlugin). 
settings( 
name := "hello-util" 


) 


自动 插件 应 该 在 文档 中 明确 指 one We a 用 ， 如 果 疑 惑 一 个 插件 是 否 已 经 局 
用 ， 可 以 在 交互 模式 下 使 用 命 令 plugins 来 判断 ,例如 


> plugins 

In file:/home/jsuereth/projects/sbt/test-ivy-issues/ 
sbt.plugins.IvyPlugin: enabled in scala-sbt-org 
sbt.plugins.JvmPlugin: enabled in scala-sbt-org 
sbt.plugins.CorePlugin: enabled in scala-sbt-org 
sbt.plugins.JUnitXmlReportPlugin: enabled in scala-sbt-org 


这 块 显示 的 是 所 有 默认 开启 的 插件 ，sbt 默认 局 用 三 个 插件 : 


e CorePlugin: 提供 并 行 任务 的 控制 
e lvyPlugin : 提供 依赖 模块 的 发 布 、 解 析 机 制 
e JvmPlugin : 提供 编译 、 测 试 、 打 包 Scala/Java 代 码 机 制 


另外 JunitxmlReportPlugin 插件 只 要 是 提供 生成 junit-xml 文件 的 支持 


添加 老 版 非 自动 插件 经 常 需要 显 式 的 配置 ， 插 件 文档 将 会 指出 如 何 进 行 配置 ， 典 型 的 老 版 插 
件 是 由 基础 配置 和 自 定 义 配 置 构成 。 


> 


例如 ， 对 于 sbt-site 这 个 插件 ， 用 如 下 配置 来 启用 该 插件 : 


site.settings 


如 果 是 多 项 目 构 建 ， 可 以 直接 在 项 目 配置 中 配置 : 


// don't use the site plugin for the `util` project 
lazy val util = (project in file('"util")) 


// enable the site plugin for the ‘core project 


lazy val core = (project in file('"core")). 
settings(site.settings : _*) 


全 局 插件 


插件 可 以 通过 在 -/.sbt/0.13/plugins/ 下 一 次 申明 配置 应 用 在 多 个 项 目 
中 ， -/.sbt/0.13/plugins/ 是 一 个 sbt 项 目 ， 其 classpath 将 导出 到 每 个 sbt 构 建 项 目 中 ， 粗 略 
的 讲 ， 在 -/.sbt/0.13/plugins/ 中 的 任何 ,sbt 或 .scala 配置 都 会 影响 到 所 有 的 Sbt 构 建 项 目 


可 以 在 -/.sbt/0.13/plugins/build.sbt 通过 addsbtplugin 方法 添加 一 个 插件 来 应 用 到 所 有 的 
项 目 中 ， 所 以 如 果 添 加 一 些 针 对 机 器 的 环境 变量 等 的 场合 这 个 特性 非常 实用 。 


已 经 存在 的 插件 
已 经 存在 的 插件 列表 


一 般 比 较 常 用 的 有 两 类 : 


o 针对 某 些 IDE 的 插件 
© 针对 Web 框 架 支持 的 插件 ， 如 xsbt-web-plugin 


自 定 义 配 置 和 任务 
置 


定义 一 个 配 
在 配置 文件 .sbt 这 章 已 经 将 了 如 何 定义 个 配置 ， 大 部 分 配置 定义 在 Default 中 


配置 有 三 种 类 型 ， 其 中 SettingKey 和 TaskKey 已 经 在 配置 文件 .sbt 介 绍 了 ，InputKey 在 任务 配 
置 的 输入 章节 介绍 。 


对 于 配置 的 一 些 例子 : 


val scalaVersion = settingKey[String]("The version of Scala used for building.") 
val clean = taskKey[Unit]("Deletes files produced by the build, such as generated sour 
ces, compiled classes, and task caches.") 


创建 配置 的 构造 方法 有 两 个 参数 ， 分 别 是 配置 的 名 称 ("scalaVersion") 和 一 个 描述 该 配置 的 字 
{t Æ ("The version of scala used for building.") ° 


在 配置 文件 .sbt 中 介绍 在 SettingKey[T] 中 的 T 表 示 该 配置 值得 类 型 ， 在 TaskKey[T] 中 T 代 表 该 
任务 返回 的 类 型 。 并 且 也 介绍 了 一 个 参数 配置 是 一 个 常量 ， 其 在 项 目 加 载 的 时 候 就 初始 化 好 
了 ， 而 一 个 任务 配置 是 可 以 重复 执行 的 (任何 时 候 在 交互 模式 下 或 批量 脚本 中 都 可 以 调用 执 
行 ) 

所 有 的 配置 都 定义 在 .sbt ，.scala 文件 或 插件 中 ， 任 何 的 在 .scala 配置 文件 中 或 在 插件 中 
的 配置 都 将 自动 的 合并 到 .spt 文件 中 。 


实现 一 个 任务 


当 定 义 完 一 个 任务 配置 后 ， 需 要 实现 一 个 任务 配置 。 可 以 自己 实现 一 个 任务 ， 也 可 以 重 载 一 
个 已 经 存在 的 任务 ， 两 者 配置 的 方式 没有 任何 区 别 。 通 过 := 方法 来 关联 任务 配置 来 实现 一 个 
任务 ， 例 如 : 


val sampleStringTask = taskKey[String]("A sample string task.") 
val samplelntTask = taskKey[Int]("A sample int task.") 
sampleStringTask := System.getProperty('"user.home") 
sampleIlntTask := { 

val sum = 1 + 2 


printin('"sum: " + sum) 
sum 


} 


如 果 一 个 任务 有 依赖 关系 ， 可 以 直接 引用 依赖 的 配置 ， 在 配置 参数 的 方法 一 章 已 经 介绍 了 。 


实现 任务 最 难 的 部 分 是 用 Scala 代 码 实现 该 任务 具体 执行 过 程 ， 例 如 ， 可 以 编写 一 个 格式 化 
HTML 的 任务 用 相关 的 HTML lib È (自己 可 以 定义 添加 一 个 依赖 库 ， 在 该 基础 上 编写 ) 


sbt 也 提供 了 一 些 工具 库 ， 例 如 常用 的 文件 和 目录 操作 API 等 。 


利用 插件 


如 果 有 许多 通用 的 代码 ， 可 以 将 其 提取 到 一 个 插件 中 ， 可 以 实现 多 项 目的 复 用 。 


ea xI .scala 


sbt 的 递归 性 


build.sbt 是 非常 简单 的 ， 其 隐藏 了 sbt 芷 正 工作 的 一 些 细节 ，sbt 是 由 Scala 语 言 编 写 的 ， 其 自 
身 也 需要 构建 ， 那 么 由 什么 好 的 办 法 来 实现 呢 ? 


project 目录 是 在 构建 项 目 中 的 另 一 个 项 目 ， 它 负责 整个 项 目的 构建 定义 ， 理 论 上 
在 project 目录 下 还 可 以 有 另 一 个 project 项 目 (递归 )， 其 构建 的 是 sbt 项 目 本 身 用 来 支撑 上 
级 项 目的 构建 。 


例如 ， 你 可 以 在 构建 项 目下 再 次 创建 一 个 项 目 ， 以 下 是 目录 层级 结构 : 


hello/ # your project's base directory 


Hello.scala # a source file in your project (could be in 
# src/main/scala too) 


build.sbt # build.sbt is part of the source code for the 
# build definition project inside project/ 
project/ # base directory of the build definition project 
Build.scala # a source file in the project/ project, 
# that is, a source file in the build definition 
build.sbt # this is part of a build definition for a project 
# in project/project ; build definition's build 
# definition 
project/ # base directory of the build definition project 
# for the build definition 


Build.scala # source file in the project/project/ project 


不 用 担心 ， 大 部 分 情况 下 是 不 需要 创建 这 个 的 ， 但 是 理解 这 个 概念 对 运用 sbt 很 有 帮助 。 


顺便 说 一 下 ， 任 何以 .sbt 或 .scala 后 级 的 定义 文件 都 会 被 用 到 ， 经 常 说 的 build.sbt 或 
Build.scala 命 名 只 是 为 了 方便 而 已 ， 也 就 是 说 sbt 配 置 支持 多 we 


.Scala 配置 文件 定 


.Sbt 文 件 定义 将 被 合并 到 子 目录 project 中 ， 例 如 如 下 项 目 目录 结构 : 


hello/ # your project's base directory 


build.sbt # build.sbt is part of the source code for the 
# build definition project inside project/ 
project/ # base directory of the build definition project 
Build.scala # a source file in the project” project, 


# that is, a source file in the build definition 


在 build.sbt 中 的 Scala 配置 表达 式 将 会 被 编译 合并 到 Build.scala 中 〈 或 者 是 在 project 目 录 下 的 
任何 .scala 文件 中 ) © 在 项 目 根 目录 的 *.sbt 文件 将 会 变 成 在 根 目录 下 project 构建 项 目 
定义 的 一 部 分 。 ,sbt 只 是 为 了 定义 项 目 方便 。 


build.sbt 和 Build.scala 的 关系 


对 于 在 构建 项 目 定义 中 混合 的 .sbt 和 .scala 定义 ， 你 需要 理解 它们 之 间 的 关系 ， 以 下 是 两 
个 文件 的 例子 ， 首 先 ， 假 设 一 个 项 目 hello ， 创 建 hello/project/Build.scala 如 下 : 


import sbt._ 
import Keys._ 


object HelloBuild extends Build { 
val sampleKeyA = settingKey[String]('"demo key A") 
val sampleKeyB settingKey[String]('"'demo key B") 
val sampleKeyC settingKey[String]('"'demo key C") 
val sampleKeyD settingKey[String]('"demo key D") 


override lazy val settings = super.settings ++ 


Seq( 
sampleKeyA := "A: in Build.settings in Build.scala", 
resolvers := Seq() 
) 
lazy val root = Project(id = "hello", 


base = file("."), 
settings = Seq( 
sampleKeyB := "B: in the root project settings in Build.scala" 


) ) 


创建 hello/build.sbt 如 下 : 


sampleKeyC in ThisBuild := "C: in build.sbt scoped to ThisBuild" 


sampleKeyD := "D: in build.sbt" 


启动 sbt 的 交互 模式 ， 输 入 inspect samplekeyA 将 会 看 到 : 


[info] Setting: java.lang.String = A: in Build.settings in Build.scala 
[info] Provided by: 
[info] {file:/home/hp/checkout/hello/}/*:samplekKeyA 


然后 输入 inspect samplekeyc 显示 如 下 : 


[info] Setting: java.lang.String = C: in build.sbt scoped to ThisBuild 
[info] Provided by: 
[info] {file:/home/hp/checkout/hello/}/*:samplekeyC 


"Provided by" 显示 这 两 个 参数 配置 的 作用 域 是 相同 的 ， 在 .sbt 文件 中 配 
置 sampleKeyC in ThisBuild 等 同 于 在 .scala 文件 中 的 Build.settings 中 配置 的 值 ， 在 上 述 两 
个 地 方 配 置 的 值得 作用 域 都 是 工程 级 别 的 作用 域 。 


现在 ， 在 查看 sampleKeyB : 


[info] Setting: java.lang.String = B: in the root project settings in Build.scala 
[info] Provided by: 
[info] {file:/home/hp/checkout/hello/}hello/*:samplekeyB 


sampleKeyB 的 作用 域 是 项 目 维度 的 ( {file:/home/hp/checkout/hello/}hello ) 不 再 是 工程 级 别 
的 作用 域 。 


你 可 能 猜 到 inspect sampleKeyD 和 sampleKeyB 的 一 样 : 


[info] Setting: java.lang.String = D: in build.sbt 
[info] Provided by: 
[info] {file:/home/hp/checkout/hello/}hello/* :sampleKeyD 


sbt 在 .sbt 文件 中 追加 配置 Build.settings 和 Project.settings 配置 的 优先 级 比 .scala 文件 
的 高 ， 所 以 配置 在 .sbt 文件 中 的 sampleC 或 sampleD 会 修改 Build.scala 的 配置 。 


另 一 个 需要 注意 的 是 : sampleKeyC 和 sampleKeyD 可 以 定义 在 build.sbt 中 定义 ， 这 是 因为 
sbt 会 将 Build 对 象 自 动 隐 式 的 导入 到 .sbt 文件 中 ， 例 如 这 个 例子 sbt 会 将 HelloBuild.” 隐 
式 的 导入 到 build.sbt 文件 中 。 


BH 2 : 


SE : 


e 在 .scala 文件 中 ， 可 以 定义 Build.settings f 配 置 项 供 sbt 查 找 ， 其 作用 域 自动 为 工程 级 别 
的 作用 域 

e 在 .scala 文件 中 ， 可 以 定义 Project.settings 配 置 项 供 sbt 查 找 ， 其 作用 域 自动 为 项 目 维 
度 的 作用 域 

e 在 .scala 文件 中 的 任何 Build 对 象 ， 都 会 自动 的 导入 到 所 有 的 .sbt 文件 中 

e .sbt 文件 中 的 配置 将 会 被 追加 到 .scala 文件 中 

e 配置 在 .sbt 文件 中 的 配置 默认 是 项 目 维度 的 作用 域 ， 除 非 手 动 指定 其 他 作用 域 


什么 时 候 用 到 .scala 配置 文件 


.scala 配置 文件 可 以 用 任何 的 Scala 代 码 编写 ， 包 括 顶 级 的 类 和 对 和 象 ， 由 于 它 是 标准 的 Scala 
语法 ， 所 以 也 没有 必须 添加 空 行 来 分 割 配置 的 限制 


在 配置 参数 配置 推荐 用 .sbt 配置 文件 ， 当 要 实现 一 些 任务 配置 或 者 要 定义 一 些 复 用 配置 供 多 
个 ,spt 文件 使 用 的 情况 推荐 使 用 .scala 配置 文件 


在 交互 模式 下 构建 项 目 


你 可 以 在 交互 模式 下 ， 切 换 到 在 project 目录 下 的 构建 工程 项 目的 项 目 中 , 当 切 换 到 该 项 目 中 
后 可 以 执行 一 些 操作 ， 如 reload plugins. 等 


> reload plugins 

[info] Set current project to default-a0e8e4 (in build file:/home/hp/checkout/hello/pr 
oject/) 

> show sources 

[info] ArrayBuffer(/home/hp/checkout/hello/project/Build.scala) 

> reload return 

[info] Loading project definition from /home/hp/checkout/hello/project 
[info] Set current project to hello (in build file:/home/hp/checkout/hello/) 
> show sources 

[info] ArrayBuffer(/home/hp/checkout/hello/hw.scala) 

> 


正如 上 面 的 例子 ， 你 可 以 用 reload return 命令 来 退出 当前 工程 构建 项 目的 项 目 ， 回 到 常规 的 
项 目 中 。 


不 可 变 配 置 


sbt 配置 可 能 被 错误 的 理解 为 在 build.sbt 的 配置 将 会 被 添加 到 Build 或 Project 对 象 的 settings 
字段 中 ， 其 实 settings 是 Build 和 Project 的 列表 ，build.sbt 中 的 配置 将 会 被 和 一 个 不 可 变 的 配 
置 列 表 连 接 起 来 生成 一 个 新 的 列表 供 sbt 使 用 的 ，Build 和 Project 中 的 “不 可 变 配置 "列表 仅仅 
是 完成 sbt 配 置 的 一 部 分 。 


事实 上 ， 还 有 其 他 的 配置 文件 ， 它 们 将 会 按照 如 下 顺序 添加 : 


e 配置 在 .scala 文件 中 的 Build.settings 和 Project.settings 配 置 项 

eo 用 户 全 局 配置 ， 例 如 在 ~-/.sbt/6.13/global.sbt 文件 中 可 以 配置 影响 所 有 工程 构建 的 配置 
项 

o 通过 被 插件 注入 的 配置 项 

e 项 目 中 .spt 文件 配置 的 配置 项 

。 构建 工程 项 目的 项 目 (例如 : 所 有 项 目 中 的 project 项 目 ) 从 全 局 插件 中 添加 的 配置 项 


后 面 的 配置 将 会 重 载 前 面 的 配置 ， 最 后 生成 一 个 配置 列表 。 
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sbt 核 心 概念 


基于 Scala， 由 于 sbt 是 基于 Scala 编 写 的 ， 所 以 相关 的 配置 语法 和 Scala 很 相似 

.Sbt 工程 构建 定义 

可 以 定义 一 个 大 的 Setting 对 象 序列 ， 最 后 被 转化 为 一 个 key-value 键 值 对 供 sbt 使 用 

可 以 通过 :=，+= 或 ++= 配置 一 个 配置 

配置 是 不 可 变 的 ， 仅 可 以 通过 转换 来 修改 。 例 如 ， 一 个 Setting 对 象 转 换 成 一 个 key-value 
键 值 对 后 是 构建 一 个 新 的 Map 对 象 来 修改 的 配置 的 ， 原 值 没有 任何 修改 

每 个 配置 都 有 一 个 类 型 ， 通 过 key 的 定义 来 决定 

任务 是 一 种 特殊 的 配置 ， 它 是 可 以 重复 调用 运算 的 ， 而 参数 配置 是 在 项 目 加 载 中 只 初始 
化 一 次 

作用 域 

每 个 配置 可 能 有 多 个 值 在 不 同 的 作用 域 中 

作用 域 有 三 个 维度 : 项 目 、 配 置 、 任 务 

作用 域 概 念 使 得 一 个 配置 可 以 再 每 个 项 目 、 每 个 任务 、 每 个 配置 下 都 可 能 产生 不 同 的 行 
为 

配置 维度 指 的 是 构建 类 型 ， 如 对 于 主 项 目 (main) 为 (Compile) 或 测试 为 (Test) 

项 目 维度 也 支持 工程 级 别 的 作用 域 

作用 域 具有 备 选 和 委托 的 特性 

.Sbt vs .scala 配置 文件 定义 

将 参数 配置 放 到 .sbt 配置 文件 中 ， 将 任务 配置 或 者 大 的 代码 段 配置 放 到 .scala 配置 文 
件 中 

插件 可 以 扩展 配置 

通过 addsbtplugin 方法 添加 一 个 插件 


如 果 以 上 的 概念 有 任何 疑惑 可 以 寻求 帮助 、 重 新 返回 去 阅读 或 者 在 交互 模式 下 做 一 些 试 
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祝 好 运 |! 


